Just Barely Good Enough Documentation #

One of the more controversial concepts in Agile Modeling is that agile models and agile documents are sufficient for the task at hand, or as I like to say they are just barely good enough (JBGE) . In this article I make the following critical points about a model or document (an artifact) being just barely good enough:

It is actually the most effective possible It is situational It does not imply low quality It changes over time It comes sooner than you think

Just Barely Good Enough Is Actually The Most Effective Possible #

For some reason people think that JBGE implies that the artifact isn’t very good, when in fact nothing could be further from the truth. When you stop and think about it, if an artifact is JBGE then by definition it is at the most effective point that it could possibly be at. Figure 1 is a diminishing returns graph which summarizes the value curve for an artifact being just barely good enough. Value refers to the net benefit of the artifact, which would be calculated as benefit - cost. The dashed line is at the point where the artifact is JBGE: anything to the left of the line implies that you still have work to do, anything to the right implies that you’ve done too much work. When you are working on something and it isn’t yet sufficient then you can still invest more effort in it and gain benefit from doing so (assuming of course you actually do work that brings the artifact closer to it’s intended purpose). However, if an artifact is already JBGE (or better) then doing more work on it is clearly a waste: once an artifact fulfills its intended purpose then any more investment in it is simply busy work. The diagram is a little naive because it is clearly possible for the value to be negative before the artifact becomes barely good enough although for the sake of argument I’m going to assume that you do a good job right from the beginning.

Ideally all of your artifacts should be JBGE, as you see in the diagram. Unfortunately, it isn’t an ideal world. You’ll often put too much effort into an artifact, unintentionally overshooting the mark as you work on it. For example, do I really need the arrowhead on the rightmost end of the value curve in Figure 1? If not, then the diagram is more than just barely good enough. Agile modelers are only human and they are not always going to do a perfect job, so realistically some artifacts are going to be more than just barely good enough. The secret is to learn how to detect when you’ve reached the point of something being just barely good enough and then to stop working on it. Easy to say, hard to do.

Just Barely Good Enough is Situational #

The fundamental challenge with JBGE is situational. For example, I often drawn UML Sequence diagrams on a whiteboard to explore complex logic and then discard it once I’m done with it (see below). In this case the whiteboard diagram is fine because it helps me to solve the issue which I’m thinking through with whomever I’m working. But, what if we’re in a situation where we’ll need to update this logic later on AND will want to do it via the diagram instead of via source code? Clearly a hand-drawn sketch isn’t good enough in this case and we’ll want to create a detailed diagram using a more sophisticated tool like PlanyUML. We’d still create an agile model even though it is much more sophisticated than a sketch because JBGE reflects the needs of the situation (remember, agile modelers Model With A Purpose).

To determine if an artifact is JBGE you must actively work with the direct audience of that artifact. In the case of system overview documentation that would be the maintenance programmers, in the case of a user manual that would be the end users, and in the case of a sketch sequence diagram that would be the programmer implementing the corresponding code. Without knowing what the audience wants, you cannot realistically create something which is JBGE, putting you in a situation where you’re motivated to put far more effort into the artifact than you need to. This often proves to be wasted effort, because chances are very good that the artifact will fall prey to the they aren’t going to read it (TAGRI) principle. To ensure that you know what the audience of an artifact wants, you need to ensure good communication with them and better yet strive for active stakeholder participation.

Just Barely Good Enough Does Not Imply Low Quality #

Some people seem to think that artifacts which are JBGE will be of low quality. The reality is that they are of sufficient quality for the job at hand. This isn’t an excuse for doing a poor quality job because quality is in the eye of the beholder: the audience for an artifact determines if it is sufficient, not the creator of it. If your stakeholders require an excellent, detailed artifact then it is JBGE when it reaches that point of being excellent and detailed.

Just Barely Good Enough Changes Over Time #

An artifact can move along this value curve in both directions throughout it’s lifecycle. Your needs may change, becoming either more complex or less so, and therefore you may choose to update your artifact(s) accordingly. If the artifact becomes less than good enough then you will need to consider updating it.

If an artifact is more than good enough should you rework it? Only if it is harming your efforts elsewhere. For example, a hand drawn diagram would have been sufficient for Figure 1 although at the time that I drew it I didn’t have easy access to any writing materials (such as paper or a whiteboard) so I used Microsoft Visio instead. Later, when I did have access to such materials I didn’t bother to replace the diagram because that would also have been useless busy work. Yes, I invested too much effort when I created the diagram because it took me almost 15 minutes to draw it with Visio yet I could have drawn this diagram on a whiteboard, taken a picture of it, and cleaned it up with software in less than five minutes. But, investing an additional five minutes to change the format of the diagram wouldn’t make any sense.

For a second example, let’s say I don’t like the current heading along the X axis and believe that Expenditure would be better. Would it be worth the effort of starting up Visio, reading in the document, updating it, generate the GIF, upload the image to my ISP, edit the HTML for this page to rework the text to match the diagram, upload the HTML, open up my browser and look at this article to ensure that I got it right, do any necessary fixes and subsequent uploads, and then commit the changes to version control? Sounds like at least five to ten minutes of effort for almost no value. Agile modelers Update Only When It Hurts, and the current X axis heading doesn’t hurt enough to warrant this investment (actually, I think the current heading makes sense). In fact, this sort of update would actually decrease the value of this article because the cost is greater than the benefit.

It Comes Sooner Than You Think #

The diagram below depicts a more realistic version, specific to modeling, of the ideal graph shown at the beginning of this article. It shows two value curves, the dashed one indicating the theoretical value of modeling according to traditional/heavy approaches and the solid line which I believe to be the actual value curve.

Traditionalists seem to assume that significant investment in modeling, and corresponding specification, will continue to add value over time. Practice, however, shows that the value in modeling comes through improved communication and ability to think things through, and that this value peaks rather quickly. For example, for initial up-front modeling this typically occurs after several days or a couple of weeks (naturally for high-risk projects you may want to invest a bit more time with initial modeling). Even for enterprise architecture or enterprise business modeling you still only want to invest a couple of weeks on initial modeling. For iteration modeling it’s even shorter, usually just an few hours, and for model storming on the order of minutes.

General Thoughts about Practices #

Apply Modeling Standards #

This practice is adapted from Coding Standards, the basic idea is that developers should agree to and follow a common set of modeling standards on a software project. Just like there is value in following common coding conventions, clean code that follows your chosen coding guidelines is easier to understand and evolve than code that doesn’t, there is similar value in following common modeling conventions.

There are a wide variety of common modeling standards available to you, including the Object Management Group’s Unified Modeling Language (UML) which defines the notation and semantics for common object-oriented models. While not every situation can me modeled using UML, a vast majority can be and for anything critical that doesnt map, feel free to use another approach to communicate the design.

Apply Patterns Gently #

Effective modelers learn and then appropriately apply common architectural, design and analysis patterns in their models. However, as Martin Fowler points out in Is Design Dead? developers should consider easing into the application of a pattern, to apply it gently. This reflects the value of simplicity.

In other words, if you SUSPECT that a pattern applies you should model it in such a way as to implement the minimal amount you need today but that makes it easy to refactor it later when it is clear that applying the full-fledged pattern is in fact the simplest approach possible. In other words, don’t over model.

For example, you may recognize a good spot in your design to apply the GoF’s Strategy pattern, but at the current moment you only have two algorithms to implement. The simplest approach might be to encapsulate each strategy in its own class and build an operation that chooses them appropriately and passes them the appropriate input. This is a partial implementation of Strategy that leaves you in a position to refactor your design if more algorithms need to be implemented, yet does not require you to build all the scaffolding that Strategy requires – an approach that enables you to ease into application of the pattern.

Discard Temporary Models #

The vast majority of the models that you create are temporary/working models – design sketches, low fidelity prototypes, index cards, potential architecture/design alternatives, and so on – models that have fulfilled their purpose but no longer add value now that they have done so. Models quickly become out of sync with the code, and there is nothing wrong with that. You must then make the decision to synchronize the models if doing so adds value to your project or to simply discard them because the investment to update the models won’t be recouped by the value of having done so (there’s negative payback).

Formalize Contract Models #

Contract models are often required when an external group controls an information resource that your system requires, such as a database, legacy application or information service. A contract model is something that both parties should mutually agree to and mutually change over time if required.

Examples of contract models include the detailed documentation of an application programming interface (API), a file layout description, an XML DTD or a physical data model describing a shared database. As with a legal contract, a contract model often requires you to invest significant resources to develop and maintain the contract to ensure that it’s accurate and sufficiently detailed.

Your goal is to minimize the number of contract models for your system to conform to the XP principle of traveling light. Note that you will almost always use an electronic tool to develop a contract model because the model must be maintained over time.

Update Only When It Hurts #

You should update a model only when you absolutely need to, when not having the model updated is more painful than the effort of updating it.

With this approach you discover that you update a smaller number of models than you would have in the past because the reality is that your models don’t have to be perfect to provide value. The street map that I have to my town is over five years old, I know this because my own street doesn’t appear on it and it’s been in place for a little over five years, yet the map is still useful to me. Yes, I could purchase an updated map, one comes out every year, but why bother? Missing a few streets isn’t painful enough to warrant this investment, it simply doesn’t make sense to spend the money to purchase a new map every year when the one that I have is good enough. Too much time and money is wasted trying to keep models and documents in sync with source code, an impossible task to begin with, time and money that could be better spent developing new software.